docs/source/api/tutorials/Tutorial 2 - Read and Write.ipynb

{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Read and Write"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import random\n",
    "\n",
    "import xgi"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Importing and exporting hypergraph data\n",
    "\n",
    "When working with empirical hypergraph data, the following file formats representing hypergraphs are commonly seen in practice:\n",
    "* A hyperedge list, where each line represents a hyperedge\n",
    "* A bipartite edge list where each line contains two entries: a node ID and an edge ID\n",
    "* An incidence matrix\n",
    "\n",
    "The `readwrite` module provides functionality to import and export these file formats."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example hypergraph"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "n = 10\n",
    "m = 10\n",
    "\n",
    "min_edge_size = 2\n",
    "max_edge_size = 10\n",
    "\n",
    "# hyperedge list\n",
    "hyperedge_list = [\n",
    "    random.sample(range(n), random.choice(range(min_edge_size, max_edge_size + 1)))\n",
    "    for i in range(m)\n",
    "]\n",
    "H = xgi.Hypergraph(hyperedge_list)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### JSON\n",
    "\n",
    "These functions import and export the hypergraph to a standardized JSON format."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Write the example hypergraph to a JSON file\n",
    "xgi.write_json(H, \"hypergraph_json.json\")\n",
    "# Load the file just written and store it in a new hypergraph\n",
    "H_json = xgi.read_json(\"hypergraph_json.json\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Edge List\n",
    "\n",
    "These functions import and export the hypergraph as an edge list, with user specified delimiters."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Write the hypergraph to a file as a hyperedge list\n",
    "xgi.write_edgelist(H, \"hyperedge_list.csv\", delimiter=\",\")\n",
    "# Read the file just written as a new hypergraph\n",
    "H_el = xgi.read_edgelist(\"hyperedge_list.csv\", delimiter=\",\", nodetype=int)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Bipartite Edge List\n",
    "\n",
    "These functions import and export the hypergraph as a bipartite edge list with user-specified delimiters."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Write the hypergraph as a bipartite edge list\n",
    "xgi.write_bipartite_edgelist(H, \"bipartite_edge_list.csv\", delimiter=\",\")\n",
    "# Read the file just written as a new hypergraph\n",
    "H_bel = xgi.read_bipartite_edgelist(\n",
    "    \"bipartite_edge_list.csv\", delimiter=\",\", nodetype=int\n",
    ")"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3.10.4 ('hypergraph')",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.13"
  },
  "orig_nbformat": 4,
  "vscode": {
   "interpreter": {
    "hash": "fdeb83b6e5b2333358b6ba79181fac315f1a722b4574d7079c134c9ae27f7c53"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}